/**
 * 支付服务接口 - 支付订单和支付流程的核心业务接口
 *
 * 开发人员：徐少洋
 * 开发时间：2025-10-25 至 2025-10-28
 * 模块职责：定义支付订单的完整业务流程接口，支持订单创建、状态管理、支付集成等功能
 *
 * 技术要点：
 * - 支付订单的创建和管理机制
 * - 多租户支付数据隔离处理
 * - ZPAY支付平台集成和签名处理
 * - 支付状态流转和异常处理
 * - 商品支付和直接支付双模式支持
 *
 * 开发故事：负责支付服务接口的设计和定义，与支付控制器和ZPAY支付平台深度配合，为企业提供稳定可靠的支付服务能力。
 */
package com.pbl.service;

import com.pbl.entity.PaymentOrder;

import java.math.BigDecimal;
import java.util.Map;

public interface PaymentService {
    /**
     * 创建普通支付订单（直接支付）
     * @param enterpriseId 企业ID
     * @param userId 用户ID
     * @param name 商品名称
     * @param amount 支付金额
     * @param payType 支付类型
     * @return 支付订单对象
     */
    PaymentOrder createOrder(Long enterpriseId, Long userId, String name, BigDecimal amount, String payType);

    /**
     * 创建商品支付订单（关联产品）
     * @param enterpriseId 企业ID
     * @param userId 用户ID
     * @param productId 产品ID
     * @param name 商品名称
     * @param amount 支付金额
     * @param payType 支付类型
     * @return 支付订单对象
     */
    PaymentOrder createOrderWithProduct(Long enterpriseId, Long userId, Long productId, String name, BigDecimal amount, String payType);

    /**
     * 根据商户订单号查询支付订单
     * @param outTradeNo 商户订单号
     * @return 支付订单对象
     */
    PaymentOrder getByOutTradeNo(String outTradeNo);

    /**
     * 标记支付成功
     * @param outTradeNo 商户订单号
     * @param tradeNo 平台交易号
     * @return 更新后的支付订单对象
     */
    PaymentOrder markSuccess(String outTradeNo, String tradeNo);

    /**
     * 关闭支付订单
     * @param outTradeNo 商户订单号
     * @return 更新后的支付订单对象
     */
    PaymentOrder closeOrder(String outTradeNo);

    /**
     * 组装ZPAY支付请求参数（开发环境模拟）
     * @param outTradeNo 商户订单号
     * @param type 支付类型
     * @param name 商品名称
     * @param amount 支付金额
     * @param notifyUrl 异步通知地址
     * @param returnUrl 同步跳转地址
     * @return ZPAY支付请求参数
     */
    Map<String, String> buildZpayParams(String outTradeNo, String type, String name, String amount, String notifyUrl, String returnUrl);
}
